WebWork 2 : Resources Available to Velocity Views
This page last changed on Dec 10, 2004 by sutter2k.

Summary

Here's the quick summary of the references available to Velocity templates that are kicked-off from WebWork:

  • $actionInstanceVariable
  • $req - the current HttpServletRequest
  • $res - the current HttpServletResponse
  • $stack - the current OgnlValueStack
  • $ognl - an OgnlTool
  • $webwork - an instance of WebWorkUtil
  • $action - the current WebWork action
  • $taglib (or something like that) - access to the JSP tag library via Velocity macros (!!)

Detail


$actionInstanceVariable
Each of your action class instance variables (for which you've written a getter method) are available in your Velocity template as $actionInstanceVariableName.

In other words, if you have an instance variable in your Action class: 

public class ProcessEditTableRowAction extends ActionSupport {
  private String fooString;

And you have a getter method for that string (in that same ActionClass):
public String getFooString() { return fooString; }

Then in your Velocity template you can retrieve the value of that String by simply refering to: 

$fooString

Note: For the most part you don't have to worry about lettercase. If your Velocity reference is $fooString (note the lowercase "f" in foo) and your getter method is called getFooString (note uppercase "F" in foo) then WebWork does the "right thing" and uses getFooString() to retrieve the value of $fooString.

But things can get weird is some circumstances. TODO: At least I think they can get weird. At one point, I remember having a problem with the lettercase of Velocity variable names and the corresponding getter methods that was being used to lookup the value. But I can't remember exactly how the problem manifested so can't provide an example. Need to do that.

TODO: I'm curious what takes care of translating the $variableName references to method calls on the Action object's getters. Where does that happen?


$req
The current HttpServletRequest created and managed by your Servlet environment (Tomcat, Resin, etc.).


$res
The current HttpServletResponse created and managed by your Servlet environment (Tomcat, Resin, etc.).


$stack
The OGNL value stack. (API Docs)

TODO: Talk about what's actually on the stack. Doesn't do a whole lot of good to know it's there without knowing what's on it.


$ognl
A reference to an OGNL tool. (API Docs)
(See OGNL Basics)

At the time of this writing, there are no docs for that object, so if you really want to know how it works, be a Jedi and "use the source". (The CVS repository is browsable here: https://webwork.dev.java.net/source/browse/webwork/src/java)


Tip:
Jason/Patrick note that one nifty thing you can do with this tool is to call static class methods. That's rather handy since Velocity doesn't offer access to class variables or methods, but only to instantiate objects that have been placed in the Velocity Context. So you can't normally do things like Math.random().

To call a class method, from within Velocity template, using the OGNL tool, you do this:
$ognl.findValue("@com.acme.FooClass@FOO")

TODO: the original email detailing the above example used $value to refer to the OGNL tool, not $ognl. But the source indicates it's "$ognl" that's shared with the context. Which is right?


$webwork
A reference to the VelocityWebWorkUtil class. (API Docs)

At the time of this writing, the API docs for this object are effectively blank, so if you really want to know how it works, be a Jedi and "use the source". (The CVS repository is browsable here: https://webwork.dev.java.net/source/browse/webwork/src/java)


Tip:
Mathew notes that the VelocityWebWorkUtil class can instantiate other objects for you. This, too, is very handy since Velocity is normally constrained to only the objects that have been explicitely shared with it's context (and not something you have control over when using Velocity templates kicked off by WebWork).

To instantiate an object from a Velocity page (that's been kicked off by WebWork, of course) do this:

#set($object = $webwork.bean("com.foo.ClassName"))

This technique can be particularly handy for grabbing a reference to one of the VelocityTools objects. (The VelocityTools are not included with WebWork, you'll need to go grab the lib and put it in your classpath if you want to use $webwork.bean() to grab references to the tool objects.)

(Note: If you're rumaging through the source, the source-code for the $webwork.bean() method above is really in VelocityWebWorkUtil's parent class WebWorkUtil.)


$action
A reference to the action context that called this template. TODO: Not really sure what's in there or what it's good for. Should probably note that.


#tag and #bodytag#

Provides a way of using a JSP taglib from velocity.
Many, but not all taglibs can be used.

ex: 
#tag( Text "name='title.edit'" )

provides a way to uses the <ww:text name="title.edit" /> tag from velocity.

Note the <ww:text /> is probably not that useful from velocity since 

$action.getText('title.edit')
would perform the same thing.

see UI tags#WW/UI+Tags for more information about webworks tags. Many provide equivalent velocity examples. Usage with other tags could be infered based on examples given.
Document generated by Confluence on Dec 14, 2004 16:36